core_extensions 1.5.3

Extensions for core/std library types, and other miscelaneous features.
Documentation

Rust crates.io api-docs

Extension traits for many standard/core library types/traits. and other miscelaneuous types / traits / functions / macros.

Adding as dependency

This crate requires cargo features for enabling items, to get all of them you can use:

[dependencies.core_extensions]
version = "1.5"
features = [
    # enables items that use anything from the standard `std` or `alloc` crates.
    "std",
    # Requires the latest stable release, enables all the rust-version-dependent features
    "rust_latest_stable",
    # enables all the item features 
    "all_items",
]

The "std" feature is required to enable impls and items that use std types, otherwise only the core library is supported.

"rust_latest_stable" enables all the "rust_1_*" crate features to use the newest stable language features, here's a list of all the "rust_1_*" features,

"all_items" enables all of the features for enabling items from this crate (documented here):

Here is the expanded version of the above configuration:

[dependencies.core_extensions]
version = "1.5"
features = [
    "std",
    "rust_latest_stable"
    # all of the features below are what "all_items" enables
    "derive"
    "bools",
    "callable",
    "collections",
    "const_default",
    "const_val",
    "generics_parsing",
    "integers",
    "item_parsing",
    "iterators",
    "macro_utils",
    "marker_type",
    "on_drop",
    "option_result",
    "phantom",
    "self_ops",
    "slices",
    "strings",
    "transparent_newtype",
    "type_asserts",
    "type_identity",
    "type_level_bool",
    "void",
]

Examples

Showcasing some features from this crate.

quasiconst, generic constants.

The quasiconst macro allows emulating generic constants by generating a zero-sized generic type that implements the ConstVal trait, the preferred way to get its value is the getconst macro.

This example demonstrates how you can use them to declare a generic VTABLE constant.

use core_extensions::{getconst, quasiconst};

use std::fmt::{self, Debug};


quasiconst!{
    pub const VTABLE<T: Debug>: &'static Vtable = &Vtable {
        size: std::mem::size_of::<T>(),
        align: std::mem::align_of::<T>(),
        drop: drop_erased::<T>,
        fmt: debug_fmt_erased::<T>,
    };
}

fn main() {
    const VTABLE_U8: &'static Vtable = getconst!(VTABLE<u8>);
    assert_eq!(VTABLE_U8.size, 1);
    assert_eq!(VTABLE_U8.align, 1);

    const VTABLE_USIZE: &'static Vtable = getconst!(VTABLE<usize>);
    assert_eq!(VTABLE_USIZE.size, std::mem::size_of::<usize>());
    assert_eq!(VTABLE_USIZE.align, std::mem::align_of::<usize>());

    const VTABLE_STRING: &'static Vtable = getconst!(VTABLE<&str>);
    assert_eq!(VTABLE_STRING.size, std::mem::size_of::<usize>() * 2);
    assert_eq!(VTABLE_STRING.align, std::mem::align_of::<usize>());
}



pub struct Vtable {
    pub size: usize,
    pub align: usize,
    pub drop: unsafe fn(*mut ()),
    pub fmt: unsafe fn(*const (), &mut fmt::Formatter<'_>) -> fmt::Result,
}

unsafe fn drop_erased<T>(ptr: *mut ()) {
    std::ptr::drop_in_place(ptr as *mut T)
}

unsafe fn debug_fmt_erased<T>(ptr: *const (), f: &mut fmt::Formatter<'_>) -> fmt::Result 
where
    T: Debug,
{
    let this = unsafe{ &*(ptr as *const T) };
    
    Debug::fmt(this, f)
}

Cargo Features

Item features

Item features enables items from this crate.

The "all_items" feature enables all of these features, you can use it instead of the ones below if you don't mind longer compile-times.

The "all_items_no_derive" feature eanbles all the features below except for the "derive" feature, to reduce compile-times due to enabling the syn indirect dependency.

  • "type_asserts": Enables the type_asserts module, with type-level assertiosn, most useful in tests.

  • "type_identity": Enables the TypeIdentity trait, for proving that two types are equal, and converting between them in a generic context.

  • "type_level_bool": Enables the type_level_bool module, which encodes bools on the type-level.

  • "void": Enables the Void type, a type that can't be constructed, for encodign impossible situations.

Rust Version numbers

These features enable code that require some Rust version past the minimum supported one:

  • "rust_1_46": Makes TransparentNewtype and TypeIdentity associated functions that take Rc<Self> or Arc<Self> callable as methods.

  • "rust_1_51": Enables the "rust_1_46" feature, and impls of traits for all array lengths.

  • "rust_latest_stable": Enables all the "rust_1_*" features. This requires the last stable release of Rust, since more "rust_1_*" features can be added at any time.

Support for other crates

All of these are disabled by default:

  • "std": Enables std library support. Implies the "alloc" feature.

  • "alloc": Enables alloc library support.

  • "serde_": Enables serde support.

Miscelaneous features

"track_caller": Enables the "rust_1_46" feature. Changes ResultLike to allow getting the caller location in ResultLike::into_result_, and makes IsNoneError store where it was constructed.

"docsrs": Used to document the required features in docs.rs, requires Rust nightly. Doesn't enable any items itself.

no-std support

This crate works in #![no_std] contexts by default.

Supported Rust versions

This crate support Rust back to 1.41.0, requiring cargo features to use language features from newer versions.

License

core_extensions is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in core_extensions by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.